home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / psion / syscalls.3 < prev    next >
Text File  |  1995-03-31  |  18KB  |  642 lines

  1. PSIONICS FILE - SYSCALLS.3
  2. ==========================
  3. System calls (part 3)
  4. Last modified 1994-09-06
  5. ========================
  6.  
  7. See part 1 for general notes and explanations.
  8.  
  9.  
  10.  
  11. Fn $8D is used for the Window Server, and is described in the Psionics file
  12. WSERVER.
  13.  
  14.  
  15. Fn $8E Sub $00 to $10 control various parts of the hardware, and should not
  16. be used by OPL programs.
  17.  
  18.  
  19. Fn $8E Sub $11
  20. HwGetSupplyStatus
  21.     BX: 6 byte buffer
  22. Gets information about the power supply. The buffer is filled with the
  23. following data:
  24.   Offset  0 (word): main battery voltage in mV
  25.   Offset  2 (word): backup battery voltage in mV
  26.   Offset  4 (word): positive if external power is available, zero if not
  27.                     available, and negative if the detector is disabled
  28.                     because an SSD door is open.
  29. The returned voltages should be taken with a grain of salt: I have observed
  30. the following values:
  31.     1800: no main batteries
  32.     1800: low main batteries
  33.     2056: new main batteries
  34.     2300: no lithium battery
  35.     2556: lithium battery fitted
  36.  
  37.  
  38. Fn $8E Sub $12
  39. HwLcdContrastDelta
  40.     AL: step direction
  41. Alters the LCD contrast by one step, upwards if AL is between 0 and 127, and
  42. downwards if it is between 128 and 255 (all inclusive).
  43.  
  44.  
  45. Fn $8E Sub $13
  46. HwReadLcdContrast
  47.     AL: -> setting
  48. Gets the current LCD contrast setting. On a Series 3, only the bottom 4 bits
  49. are significant.
  50.  
  51.  
  52. Fn $8E Sub $14
  53. HwSwitchOff
  54.     CX: delay in quarter seconds
  55. Switches the machine off for the specified time, then back on again. The
  56. machine may also be turned on by external events. The delay must be at least
  57. 9 (2.25 seconds).
  58.  
  59.  
  60. Fn $8E Sub $15 should only be used by device drivers.
  61.  
  62.  
  63. Fn $8E Sub $16
  64. HwExit
  65.  
  66. Exits the emulation on PC systems; has no effect on actual Psion machines.
  67.  
  68.  
  69. Fn $8E Sub $17 to $1A should only be used by device drivers.
  70.  
  71.  
  72. Fn $8E Sub $1B
  73. HwGetPsuType
  74.     AL: -> PSU type
  75. Gets the PSU type: 0 = original, 1 = "Maxim", 2 = "Pan", 3 = Series 3.
  76.  
  77.  
  78. Fn $8E Sub $1C
  79. HwSupplyWarnings
  80.     BX: 8 byte buffer
  81. Gets information about the power supply. The buffer is filled with the
  82. following data:
  83.   Offset  0 (word): main battery good voltage threshold in mV
  84.   Offset  2 (word): backup battery good voltage threshold in mV
  85.   Offset  4 (word): main battery nominal maximum voltage in mV
  86.   Offset  6 (word): backup battery nominal maximum voltage in mV
  87. The values will depend on the battery type set by GenSetBatteryType.
  88.  
  89.  
  90. Fn $8E Sub $1D
  91. HwForceSupplyReading
  92. @No documentation available at present@
  93.  
  94.  
  95. Fn $8E Sub $1E
  96. HwGetBackLight
  97.     AX: -> current value
  98. On systems fitted with a backlight, this value indicates control of the
  99. backlight function. If the top bit is set, the operating system will ignore
  100. the backlight toggle key. The remaining bits give the auto-light-off time in
  101. ticks (1/32 second); zero means that auto-light-off is disabled.
  102.  
  103.  
  104. Fn $8E Sub $1F
  105. HwSetBackLight
  106.     BX: new value
  107. Sets the backlight control value (see HwGetBackLight).
  108.  
  109.  
  110. Fn $8E Sub $20
  111. HwBackLight fails
  112.     AL: action -> status before call
  113. This call fails if no backlight is fitted. Otherwise, the actions are:
  114.     0 = switch backlight off
  115.     1 = switch backlight on
  116.     2 = toggle backlight
  117.     3 = no action
  118. The status returned is that of the backlight before the call: 0 = off, 1 = on.
  119.  
  120.  
  121. Fn $8E Sub $21 controls various parts of the hardware, and should not be used
  122. by OPL programs.
  123.  
  124.  
  125. Fn $8E Sub $22
  126. HwSupplyInfo v3
  127.     BX: 22 byte buffer
  128. Fills the buffer with additional information about the power supply:
  129.   Offset  0 (byte): main battery status:
  130.     0 = not present
  131.     1 = very low voltage
  132.     2 = low voltage
  133.     3 = good voltage
  134.   Offset  1 (byte): worst main battery status since batteries last inserted
  135.   Offset  2 (byte): non-zero if backup battery voltage is good
  136.   Offset  3 (byte): non-zero if external supply is present
  137.   Offset  4 (word): warning flags
  138.     Bit 0: set if power supply too low for sound
  139.     Bit 1: set if power supply too low to use flash
  140.     Bit 2: set   if offset 6 changed because system clock changed
  141.            clear if offset 6 changed because the batteries were changed
  142.   Offset  6 (long): abstime when batteries inserted
  143.   Offset 10 (long): ticks running on battery
  144.   Offset 14 (long): ticks running on external supply
  145.   Offset 18 (long): mA-ticks (i.e. mAhours * 60 * 60 * 32)
  146.  
  147.  
  148. Fn $8E Sub $28
  149. HwGetScanCodes v3
  150.     BX: 20 byte buffer
  151. The buffer is filled with information describing the state of each key on
  152. the keyboard. For the Series 3a, the offset and bit for each key are given
  153. in the following table ("2:4" means offset 2, bit 4).
  154.     System   9:1  Esc     15:0  Delete   4:0  1 14:1  A 12:2  N  0:6
  155.     Data     7:1  Tab      0:2  Enter    0:0  2 14:2  B  8:6  O  4:5
  156.     Word    11:1  Control  4:7  ShiftR   6:7  3 10:6  C 10:3  P  2:5
  157.     Agenda   3:1  ShiftL   2:7  Up      14:5  4  8:2  D 10:4  Q 12:1
  158.     Time     1:1  Psion    0:7  Left     0:4  5  8:3  E 10:5  R  8:1
  159.     World    5:1  Menu    10:7  Down     0:5  6 14:3  F 10:1  S 12:4
  160.     Calc     3:0  Diamond  8:7  Right    0:1  7  6:6  G  8:5  T  8:4
  161.     Sheet    1:0  Space    8:0  Help     6:2  8  4:3  H 14:6  U  6:5
  162.     + and =  2:3  - and _  2:2                9  4:4  I  4:2  V 10:2
  163.     * and :  2:6  / and ;  2:1                0  2:4  J  6:4  W 12:5
  164.     , and <  6:1  . and > 14:4                        K  4:1  X 12:6
  165.                                                       L  4:6  Y  0:3
  166.                                                       M  6:3  Z 12:3
  167.  
  168.  
  169. Fn $8F
  170. GenDataSegment
  171.  
  172. This call is only useful in assembler code; it sets ES to point to the start
  173. of the kernel data space (accessible in OPL using GenGetOsData).
  174.  
  175.  
  176. Fn $90
  177. ProcPanic
  178.     AL: reason
  179. Panic the current process; this call never returns.
  180.  
  181.  
  182. Fn $91
  183. ProcCopyFromById fails
  184.     BX: process ID
  185.     CX: number of bytes to copy
  186.     SI: remote address of first byte to copy
  187.     DI: local address of first byte to copy
  188. Copy a number of bytes from the indicated process to the current process.
  189.  
  190.  
  191. Fn $92
  192. ProcCopyToById fails
  193.     BX: process ID
  194.     CX: number of bytes to copy
  195.     SI: local address of first byte to copy
  196.     DI: remote address of first byte to copy
  197. Copies a number of bytes from the current process to the indicated process.
  198.  
  199.  
  200. Fn $93
  201. CharIsDigit
  202. Fn $94
  203. CharIsHexDigit
  204. Fn $95
  205. CharIsPrintable
  206. Fn $96
  207. CharIsAlphabetic
  208. Fn $97
  209. CharIsAlphaNumeric
  210. Fn $98
  211. CharIsUpperCase
  212. Fn $99
  213. CharIsLowerCase
  214. Fn $9A
  215. CharIsSpace
  216. Fn $9B
  217. CharIsPunctuation
  218. Fn $9C
  219. CharIsGraphic
  220. Fn $9D
  221. CharIsControl
  222.     AL: character to test
  223.     EQ: -> set if test fails, clear if test succeeds
  224. Tests to see whether the character has the indicated property. These functions
  225. are language dependent.
  226.  
  227.  
  228. Fn $9E
  229. CharToUpperChar
  230. Fn $9F
  231. CharToLowerChar
  232. Fn $A0
  233. CharToFoldedChar
  234.     AL: character 1 -> converted character 1
  235.     AH: character 2 -> converted character 2
  236. Converts two characters to uppercase, lowercase, or folded (uppercase with no
  237. accents). These functions are language dependent.
  238.  
  239.  
  240. Fn $A1
  241. BufferCopy
  242.     CX: length to be copied
  243.     SI: address of "from" buffer
  244.     DI: address of "to" buffer
  245. Copies a number of bytes from one buffer to another. The case of the buffers
  246. overlapping is handled correctly.
  247.  
  248.  
  249. Fn $A2
  250. BufferSwap
  251.     CX: length to be swapped
  252.     SI: address of buffer 1
  253.     DI: address of buffer 2
  254. Swaps the contents of two buffers. The case of the buffers overlapping is
  255. handled correctly.
  256.  
  257.  
  258. Fn $A3
  259. BufferCompare
  260. Fn $A4
  261. BufferCompareFolded
  262.     BX: length of buffer 2
  263.     CX: length of buffer 1
  264.     SI: address of buffer 1
  265.     DI: address of buffer 2
  266.     UL: -> set if buffer 1 less than buffer 2
  267.     EQ: -> set if buffers are identical
  268. The contents of the two buffers are compared byte-for-byte, using unsigned
  269. comparisons, and the result flags set accordingly. BufferCompareFolded acts
  270. as if each character had been passed to CharToFoldedChar before comparison.
  271.  
  272.  
  273. Fn $A5
  274. BufferMatch fails
  275. Fn $A6
  276. BufferMatchFolded fails
  277.     CX: length of buffer
  278.     DX: length of pattern
  279.     SI: address of buffer
  280.     DI: address of pattern
  281. The buffer is searched to determine if the pattern occurs within it (using
  282. the usual wildcards); the call fails if it does not. BufferMatchFolded acts
  283. as if each character had been passed to CharToFoldedChar before comparison.
  284.  
  285.  
  286. Fn $A7
  287. BufferLocate fails
  288. Fn $A8
  289. BufferLocateFolded fails
  290.     AH: character -> [undefined]
  291.     AX: -> offset of character
  292.     CX: length of buffer
  293.     SI: address of buffer
  294. The buffer is searched to determine if the character occurs within it; the
  295. call fails if it does not. If it does, the offset from the start of the buffer
  296. of the first occurence is returned. BufferLocateFolded acts as if each
  297. character had been passed to CharToFoldedChar before comparison.
  298.  
  299.  
  300. Fn $A9
  301. BufferSubBuffer fails
  302. Fn $AA
  303. BufferSubBufferFolded fails
  304.     AX: -> offset
  305.     BX: length of buffer 2
  306.     CX: length of buffer 1
  307.     SI: address of buffer 1
  308.     DI: address of buffer 2
  309. Buffer 1 is searched to determine if buffer 2 occurs within it; the call fails
  310. if it does not. If it does, the offset from the start of buffer 1 of the first
  311. occurence of buffer 2 is returned. BufferSubBufferFolded acts as if each
  312. character had been passed to CharToFoldedChar before comparison.
  313.  
  314.  
  315. Fn $AB
  316. BufferJustify
  317.     AX: -> address of first uncopied character
  318.     BX: length of buffer 2
  319.     CX: length of buffer 1
  320.     DX: fill character * 256 + control code
  321.     SI: address of buffer 1
  322.     DI: address of buffer 2
  323. Buffer 1 is copied into buffer 2, and the remaining space filled with the fill
  324. character according to the control code (0 = fill at end, 1 = fill at start,
  325. 2 = centre the copied data). If buffer 1 is longer than buffer 2, then the
  326. contents will be truncated to fit. If the length of buffer 2 is negative, then
  327. it is assumed to be the same as that of buffer 1 (and the data is just copied).
  328.  
  329.  
  330. Fn $AC
  331. StringCopy
  332. Fn $AD
  333. StringCopyFolded
  334.     SI: cstr
  335.     DI: large enough buffer
  336. The cstr is copied into the buffer. StringCopyFolded passes each character
  337. through CharToFoldedChar during the copy.
  338.  
  339.  
  340. Fn $AE
  341. StringConvertToFolded
  342.     SI: cstr
  343. Each character of the cstr is passed through CharToFoldedChar.
  344.  
  345.  
  346. Fn $AF
  347. StringCompare
  348. Fn $B0
  349. StringCompareFolded
  350.     SI: cstr 1
  351.     DI: cstr 2
  352.     UL: -> set if cstr 1 less than cstr 2
  353.     EQ: -> set if cstrs are identical
  354. The contents of the two cstrs are compared byte-for-byte, using unsigned
  355. comparisons, and the result flags set accordingly. StringCompareFolded acts
  356. as if each character had been passed to CharToFoldedChar before comparison.
  357.  
  358.  
  359. Fn $B1
  360. StringMatch fails
  361. Fn $B2
  362. StringMatchFolded fails
  363.     SI: cstr to be searched
  364.     DI: pattern (cstr)
  365. The cstr is searched to determine if the pattern occurs within it (using
  366. the usual wildcards); the call fails if it does not. StringMatchFolded acts
  367. as if each character had been passed to CharToFoldedChar before comparison.
  368.  
  369.  
  370. Fn $B3
  371. StringLocate fails
  372. Fn $B4
  373. StringLocateFolded fails
  374. Fn $B5
  375. StringLocateInReverse fails
  376. Fn $B6
  377. StringLocateInReverseFolded fails
  378.     AH: character -> [undefined]
  379.     AX: -> offset of character
  380.     SI: cstr
  381. The cstr is searched to determine if the character occurs within it; the
  382. call fails if it does not. If it does, the offset from the start of the cstr
  383. of the first (for StringLocate and StringLocateFolded) or last (for the two
  384. Reverse calls) occurence is returned. The two Folded calls act as if each
  385. character had been passed to CharToFoldedChar before comparison.
  386.  
  387.  
  388. Fn $B7
  389. StringSubString fails
  390. Fn $B8
  391. StringSubStringFolded fails
  392.     AX: -> offset
  393.     SI: cstr 1
  394.     DI: cstr 2
  395. Cstr 1 is searched to determine if cstr 2 occurs within it; the call fails
  396. if it does not. If it does, the offset from the start of cstr 1 of the first
  397. occurence of cstr 2 is returned. StringSubStringFolded acts as if each
  398. character had been passed to CharToFoldedChar before comparison.
  399.  
  400.  
  401. Fn $B9
  402. StringLength
  403.     AX: -> length of the cstr
  404.     DI: cstr
  405. Returns the length of a cstr, excluding the terminating zero byte.
  406.  
  407.  
  408. Fn $BA
  409. StringValidateName fails
  410.     AL: maximum number of characters permitted
  411.     AH: non-zero if an extension is permitted
  412.     DI: cstr
  413. The cstr is checked to see if it a valid name, and the call fails if it is
  414. not. A name is valid if it:
  415. * begins with a letter;
  416. * contains only letters, digits, dollar signs ($), underscores (_), and at
  417.   most one dot;
  418. * if AH is zero, does not contain a dot;
  419. * contains no more than the specified number of characters before the dot
  420.   (if any); and
  421. * contains no more than 4 characters after the dot, if any.
  422. @The manual says 3 characters, but my tests accept 4.@
  423.  
  424.  
  425. Fn $BB
  426. LongIntCompare
  427.     AX: high half of P
  428.     BX: low half of P
  429.     CX: high half of Q
  430.     DX: low half of Q
  431.     SL: -> set if P less than Q
  432.     EQ: -> set if P equals Q
  433. Compares P and Q (both signed longs) and sets the result flags accordingly.
  434.  
  435.  
  436. Fn $BC
  437. LongIntMultiply fails
  438.     AX: high half of P -> high half of product
  439.     BX: low half of P  -> low half of product
  440.     CX: high half of Q
  441.     DX: low half of Q
  442. Multiples P and Q (both signed longs); the call fails if the result cannot
  443. be represented as a signed long.
  444.  
  445.  
  446. Fn $BD
  447. LongIntDivide fails
  448.     AX: high half of P -> high half of quotient
  449.     BX: low half of P  -> low half of quotient
  450.     CX: high half of Q -> high half of remainder
  451.     DX: low half of Q  -> low half of remainder
  452. Divides P by Q (both signed longs); the call fails if Q is zero. The remainder
  453. will have the same sign as P.
  454.  
  455.  
  456. Fn $BE
  457. LongUnsignedIntCompare
  458.     AX: high half of P
  459.     BX: low half of P
  460.     CX: high half of Q
  461.     DX: low half of Q
  462.     UL: -> set if P less than Q
  463.     EQ: -> set if P equals Q
  464. Compares P and Q (both unsigned longs) and sets the result flags accordingly.
  465.  
  466.  
  467. Fn $BF
  468. LongUnsignedIntMultiply fails
  469.     AX: high half of P -> high half of product
  470.     BX: low half of P  -> low half of product
  471.     CX: high half of Q
  472.     DX: low half of Q
  473. Multiples P and Q (both unsigned longs); the call fails if the result cannot
  474. be represented as a unsigned long.
  475.  
  476.  
  477. Fn $C0
  478. LongUnsignedIntDivide fails
  479.     AX: high half of P -> high half of quotient
  480.     BX: low half of P  -> low half of quotient
  481.     CX: high half of Q -> high half of remainder
  482.     DX: low half of Q  -> low half of remainder
  483. Divides P by Q (both unsigned longs); the call fails if Q is zero.
  484.  
  485.  
  486. Fn $C1
  487. FloatAdd fails
  488. Fn $C2
  489. FloatSubtract fails
  490. Fn $C3
  491. FloatMultiply fails
  492. Fn $C4
  493. FloatDivide fails
  494.     SI: address of Q
  495.     DI: address of P
  496. Calculates the specified one of P+Q, P-Q, P*Q, or P/Q, and places the result
  497. in P. Both P and Q are reals.
  498.  
  499.  
  500. Fn $C5
  501. FloatCompare
  502.     SI: address of Q
  503.     DI: address of P
  504.     SL: -> set if P is less than Q
  505.     EQ: -> set if P equals Q
  506. Compares two reals and sets the result flags appropriately.
  507.  
  508.  
  509. Fn $C6
  510. FloatNegate
  511.     DI: address of P
  512. Negates a real in-situ.
  513.  
  514.  
  515. Fn $C7
  516. FloatToInt fails
  517. Fn $C8
  518. FloatToUnsignedInt fails
  519.     AX: -> result
  520.     SI: address of real
  521. Converts a real to a signed or unsigned int; the call fails if the result is
  522. out of range. FloatToUnsignedInt ignores the sign of the real.
  523.  
  524.  
  525. Fn $C9
  526. FloatToLong fails
  527. Fn $CA
  528. FloatToUnsignedLong fails
  529.     AX: -> high half of result
  530.     BX: -> low half of result
  531.     SI: address of real
  532. Converts a real to a signed or unsigned long; the call fails if the result is
  533. out of range. FloatToUnsignedLong ignores the sign of the real.
  534.  
  535.  
  536. Fn $CB
  537. IntToFloat
  538. Fn $CC
  539. UnsignedIntToFloat
  540.     AX: value
  541.     DI: address of real
  542. Converts a signed or unsigned int to a real.
  543.  
  544.  
  545. Fn $CD
  546. LongToFloat
  547. Fn $CE
  548. UnsignedLongToFloat
  549.     AX: high half of value
  550.     BX: low half of value
  551.     DI: address of real
  552. Converts a signed or unsigned long to a real.
  553.  
  554.  
  555. Fn $CF
  556. LibSend
  557. Fn $D0
  558. LibSendSuper
  559.     AX: -> method result
  560.     BX: handle of object to receive the message
  561.     CX: message number
  562.     DX: argument 1
  563.     SI: argument 2
  564.     DI: argument 3
  565. These functions send a message to an object and invoke a method on that object.
  566. LibSend starts searching for the method in the class of the object, and
  567. LibSendSuper in the superclass.
  568.  
  569.  
  570. Fn $D1 to $D3 can only be used from assembler.
  571.  
  572.  
  573. Fn $D4
  574. Dummy
  575.  
  576. This function has no effect.
  577.  
  578.  
  579. Fn $D5
  580. GenIntByNumber
  581.     AL: Fn -> error and result flags
  582.     SI: argument block
  583.     DI: result block
  584. This call is equivalent to the OS keyword; it calls another system call with
  585. the arguments and results stored in 12 byte blocks.
  586.  
  587.  
  588. Fn $D6 is used for the Window Server, and is described in the Psionics file
  589. WSERVER.
  590.  
  591.  
  592. Fn $D7 is normally only used by the C library.
  593.  
  594.  
  595. Fn $D8 is used for accessing DBF files. See the Psionics file DBF.FMT.
  596.  
  597.  
  598. Fn $D9
  599. LibEnterSend
  600.     AX: -> method result
  601.     BX: handle of object to receive the message
  602.     CX: message number
  603.     DX: argument 1
  604.     SI: argument 2
  605.     DI: argument 3
  606. This is identical to LibSend, except that it also starts a new "entry-exit
  607. region". The method description will state when this is needed.
  608.  
  609.  
  610. Fn $DA
  611. IoKeyAndMouseStatus
  612. @No documentation available at present@
  613.  
  614.  
  615. Fn $DB
  616. StringCapitalise
  617.     SI: cstr
  618. The first character of the cstr is passed through CharToUpperChar, and the
  619. remaining characters through CharToLowerChar.
  620.  
  621.  
  622. Fn $DC
  623. ProcIndStringCopyFromById fails
  624.     BX: process ID
  625.     CX: maximum length to copy
  626.     SI: address of location holding address of cstr
  627.     DI: buffer
  628. This copies a cstr from the indicated process to the current process. The
  629. cstr is found via a pointer also in the memory of the indicated process, and
  630. the address of this pointer is specified. This call is equivalent to making
  631. two calls to ProcCopyFromById, the first to find the location of the cstr, and
  632. the second to fetch it, except that the contents of the buffer beyond the
  633. terminating zero are unspecified.
  634.  
  635.  
  636. Fn $DD is reserved for the window server.
  637.  
  638.  
  639. Fn $DE
  640. IoSerManager
  641. @No documentation available at present@
  642.